.\" groff -man -Tascii arcan.1
.TH arcan 1 "October 2015" arcan_db "User manual"
.SH NAME
Arcan_db \- Database Support tool for Arcan
.SH SYNOPSIS
.B arcan_db [-d dbfile]
.RI [COMMAND]
.B command-specific data

.SH DESCRIPTION
The arcan_db tool manages the database that arcan uses as an application
specific key-value store, but also for controlling which programs (targets) and
which set of arguments (configuration) that are allowed to be launched
by an application using Arcan.

It is also used to manage some configuration options for the arcan instance
itself. Such options are stored under the reserved appl names "arcan" and
"arcan_lwa" respectively.

It is also used to manage some configuration options for the arcan instance
itself. Such options are stored under the reserved appl names "arcan" and
"arcan_lwa" respectively.

.SH COMMAND
.IP "\fBadd_target\fR \fIname\fR \fI-tag\fR \fIbfrm\fR \fIexecutable\fR \fIargv\fR"
Create a new target or update values for a pre-existing ones. The \fIname\fR
field is a unique identifier that will be used to reference the target from
within the engine. \fIexecutable\fR should point to the binary, folder or
specific data file to be launched. \fIbfrm\fR specifies the binary format
to be loaded, where BIN corresponds to a native binary (e.g. ELF for POSIX
systems and PE on windows), LWA for using arcan-in-arcan style execution and
RETRO for a libretro- compatible core (.so or .dll).see \fIBINARY FORMATS\fR
below for details. The optional \fItag\fR argument specifies ONE application
defined selection tag. See the section on tags below for further guidance.

\fIArgv\fR can be a variable number of arguments that will be set as the base
arguments for the target. For bfrm LWA, these will be passed to the application
and will be ignored for bfrm RETRO.

A configuration named \fIdefault\fR will also be created, this configuration
cannot be deleted without deleting the target.

.IP "\fBadd_target_kv\fR \fIname\fR \fIkey\fR \fIvalue\fR"

Define or update a key/value pair assoicated with the specific target.
These values are also accessible from the context of an arcan application.

.IP "\fBadd_target_env\fR \fItargetname\fR \fIkey\fR \fIvalue\fR"

Add a key/value pair (expands to key=value internally) that will be used
to set up the environment for the program. Those that are specific for
library interposition, e.g. LD_PRELOAD may be filtered and the _target_lib
command should be used for such purposes.

.IP "\fBadd_target_lib\fR \fItargetname\fR \fIlibstr\fR"

Add a library for interpositioning, 'hijack'. These are libraries used
to replace specific function calls in the subject. The specific mechanism
for accomplishing this is implementation defined.

.IP "\fBadd_config\fR \fItargetname\fR \fIconfigname\fR \fIargv\fR"

Create or update \fIconfigname\fR in the specific target.
The arguments specified in \fIargv\fR are similar to
those used in \fIadd_target\fR but will always be appended after
the arguments associated with the target.

.IP "\fBadd_config_kv\fR \fItargetname\fR \fIconfigname\fR \fIkey\fR \fIval\fR"

Add a key/value pair associated with a configuration. This pair will be
accessible from the context of an arcan application, and may be used by
an arcan application to track client configuration specific settings.

.IP "\fBadd_config_env\fR \fItargetname\fR \fIconfigname\fR \fkey\fR \fIval\fR"

Add a key/value pair associated with a configuration. This pair will be
accessible from the environment of the executing client.

.IP "\fBadd_appl_kv\fR \fIapplname\fR \fIkey\fR \fIval\fR"

Add a key/value pair associated with an appl. This pair will be accessible
from the context of a specific arcan application matching \fIapplname\fR and
is intended for application specific persistent configuration.

.IP "\fBdrop_appl_key\fR \fIapplname\fR \fIkey\fR"

Remove the key and value from the specified appl.

.IP "\fBdrop_config\fR \fItargetname\fR \fIconfigname\fR"

Delete a specific config. This will also remove any key/values associated
with that config. The configname 'default' cannot be removed in this way.

.IP "\fBdrop_all_configs\fR \fItargetname\fR"

Delete all configs for the specific target. This act as a "for each config in
target, drop_config" and will thus purge the keys associated with the configs
as well.

.IP "\fBdrop_target\fR \fItargetname\fR"

Delete the specific target and all associated configurations, environment
library and key/value pairs.

.IP "\fIdrop_appl\fR \fIapplname\fR"

Delete all keys associated with the specific application name.

.SH TAGS
Each target can be associated with a tag. These have application specific
meaning, though a generalized suggested set of tags that are also respected
by hook-scripts where applicable are as follows:

\fBautorun\fR - Should be used to select targets that should be launched
upon startup, this includes all configurations attached to that target.

\fBhidden\fR - Should be used to prevent targets from being listed in
user interfaces that allows the user to pick targets that can be launched.

\fBautorun_hidden\fR - Combines the behavior from the tag 'autorun' and from
the tag 'hidden'. This is suggested for hook scripts that want to manage
external connection points that should be invisible to the running application.

.SH SCRIPTING MODE
To assist when using this program as a database interface for a script, a
single dash can be specified instead of the command. In that case, the program
will process line- separated input from STDIN where each element is separated
with a tab character. The command format is otherwise the same as regular
usage. In addition, the program will output 'OK' or 'FAIL' to stderr in
response to each command (while stdout will contained the more detailed error
description).

.SH BINARY FORMATS
The currently supported binary formats are \fBBIN\fR, \fBLWA\fR, \fBSHELL\fR,
\fBEXTERNAL\fR and \fBGAME\fR. Binary format specifies how the new process
will be created when launching a target/configuration pair.

For \fBBIN\fR, the argv, envv and libs are treated with expanding namespaces.
This means that all entries will have [ARCAN_XXXPATH] fields being replaced with
the respective namespace expansion. Libs will, in turn, be added to the
LD_PRELOAD, DYLD_INSERT_LIBRARIES or some other implementation defined
hijack/interposition technique. (Corresponding fields may be fileted from env).

For \fBSHELL\fR, the \fBBIN\fR expansion rules apply, but indicate that it
should be launched / monitored as a shell. This currently has no further
semantic meaning (and is internally aliased as BIN) but reserved for future use.

For \fBEXTERNAL\fR, the \fBBIN\fR expansion rules apply, but indicate that the
engine should suspend all operations (or maintain an audio/video/frameserver-
less pipeline) and release as much resources as possible,
until the target/configuration has finished executing.

For \fBLWA\fR, (currently not implemented, scheduled for 0.6) arcan_lwa will
be used as a loader, with similar expansion to envv. Libs- list will be ignored.

For \fBGAME\fR, the fsrv_game frameserver will be used as a chainloader. The
target executable with be expanded into the core to be run, the first (optional)
argument aded to the \fBconfiguration\fR will be the resource to pass on and the
seocond (also optional) argument defines the system- path.

.SH NOTES
There is also a number of list/show_ commands that are listed if you run the
program without any arguments. These are not intended as a serialization
or interfacing tool, interface with the arcan_db.c / arcan_db.h for those
kinds of purposes.

.SH SEE-ALSO
.IX Header "SEE ALSO"
\&\fIarcan\fR\|(1)

.SH BUGS
You can report bugs at the forum on the homepage or through the the AUTHOR
contact below. Save a snapshot of core-dumps (in the case of engine issues) or
the appropriate resources/logs entries. For some issues, a copy of the database
used and a list of files (with permissions) in applpath and
resourcepath might also be relevant.

.SH COPYRIGHT
Copyright  ©  2014-2018  Bjorn Stahl. License 3-clause BSD. This is free software:
you are free  to  change  and  redistribute  it. There is NO WARRANTY,
to the extent permitted by law.

.SH AUTHOR
Bjorn Stahl <contact at arcan-fe dot com>
